-*-Setx-*-


# Manipulate Columns Tutorial
=============================

This is a tutorial that demonstrates the "manipCols" feature. In  order  to
use it, you must first activate the feature  by  going  to  the  menu  item
"Alpha --> Global Setup --> Features" and selecting  'Manip  Cols'  in  the
features list by checking the corresponding checkbox.

The 'manipCols' package is  a  feature  which  allows  one  to  do  various
manipulations with the columns of any tabulated material, i.e. a series  of
lines in which items are separated by a tabulation or by any other specific
character (like & or a tabulation or a colon, a comma, an  endash  etc.  or
even the space character). Once it is installed and activated,  it  adds  a
submenu called "Columns" to the "Text" menu in Alpha.  The  items  of  this
submenu are explained below. Basic manipulations  are  copying,  inserting,
appending, twiddling,  deleting,  sorting,  numbering  and  (un/)equalizing
columns, formating text in a rectangle.

This Tutorial, when opened through a hyperlink, is a "shell"  window.  None
of the changes you make will affect the  actual  file.  If  you  close  the
window and then click on the hyperlink again, you will start with the  same
example as before.  Note that "Undo" is not available in shell windows.

This tutorial is in Setx mode to take advantage of some  file  marking  and
colorizing procedures. The manipCols feature can work in any mode.


# Columns selection
===================


To select one or several columns, put the cursor anywhere in  the  text  of
the top left item (or "cell") you want to select, press  the  mouse  button
and,  without releasing the button, go to the text of the bottom right item
you want to select.

This will hilite a region which is much more than what  you  want  but  the
package will consider only the columns located between the top  and  bottom
positions.

Here is an example (from Romeo and Juliet). We suppose here that each  word
is separated by a tabulation (any single  character  can  be  chosen  as  a
separator, even the space character; see below) :

Gallop	apace,	you	fiery footed	steeds,
Towards	Phoebus'	lodging;	such	a	waggoner
As	Phaethon	would	whip	you	to	the	west,
And	bring	in	cloudy	night	immediately.

Put the cursor in the word 'you' (first row, third word), press  the  mouse
button and, without releasing it, go to the word 'whip' in the  third  row,
then release. Now use the "Text --> Columns --> Copy  Columns"  menu  item.
Now paste it here:




you should have selected the following region

you	fiery footed
lodging;	such
would	whip

even though all the words from 'you' to 'whip' are hilited.  We  have  thus
selected columns 3-4 and rows 1-3.



# Equalizing Columns
--------------------


If you want to have a better vertical alignment of your columns you can use
the "Equalize Columns" menu item. Select the region as above (or the entire
selection) and select "Equalize Columns" in the "Text --> Columns" menu.

Gallop	apace,	you	fiery footed	steeds,
Towards	Phoebus'	lodging;	such	a	waggoner
As	Phaethon	would	whip	you	to	the	west,
And	bring	in	cloudy	night	immediately.

The result should be :

Gallop 	apace,  	you     	fiery footed	steeds,
Towards	Phoebus'	lodging;	such        	a      	waggoner    
As     	Phaethon	would   	whip        	you    	to          	the	west,
And    	bring   	in      	cloudy      	night  	immediately.

By the way, equalizing makes it very easy to  use  rectangular  hiliting  :
now try to select a region with the mouse holding the option key down.


# Notes regarding column selection
-------------------------------------

• the cursor can be positioned anywhere in a "cell": the entire column will
always be selected.

• columns are numbered from 1 to n (see the messages in the status bar).

• hiliting must still be there if you want to apply a manipulation like
copying, inserting, appending, twiddling, deleting columns.

• note that you DO NOT have to escape (i-e put a backslash before) the
special characters like 'backslash' \ or 'dollar' $ or 'circumflex' ^ or
'endash' - etc. The package takes care of this internally. The tabulation
character though is represented by '\t'.

• all the actions are undoable (with cmd-Z), except in this tutorial
"shell" window.


# Column Selection Key Bindings
-------------------------------

All of the menu items that you have just used are also available through
key bindings. All the key bindings will use 'ctrl-c' (c for columns !).

Hit 'ctrl-c', release, then hit one of the following letters :

	<ctrl-c c>    to <c>opy columns
	<ctrl-c d>    to <d>elete columns
	<ctrl-c i>    to <i>nsert columns
	<ctrl-c x>    to cut columns (e<x>tract them and copy in clipboard)


The menu item "Text --> Columns -> Columns Utilities -> Columns Bindings"
will display all of the key bindings available.


# Columns separator
-------------------

The Columns separator must NECESSARILY be a SINGLE character. 

The default is the tabulation character <\t>. Changing the separator can be
done using the "Columns Separator" menu item, which is bound to <ctrl-c s>.
This separator will remain changed throughout the remainder of your Alpha
session or until you chang eit again. 

The "Config --> Packages --> Manip Cols Prefs" menu item includes a
preference for the default separator.

With Latex you might want to choose '&' as a separator for \array or \table
environments:

    \begin{tabular}{|c|c|c|}
	\hline
    you & fiery-footed \\
    lodging; & such \\
    would & whip \\
	\hline
    \end{tabular}

You can even use the 'space' character as a separator.


# Rectangle Text 
================

This formats text in a fully  justified  column.  This  is  very  handy  to
prepare nice looking documentations, help files, etc. All the paragraphs in
the present  file  have  been  justified  with  this  tool.  Everything  is
parametrizable: number of columns, left margin, text width.

Highlight this entire selection, and then use the  "Rectangle  Text"  item.
(This is also bound to <ctrl-c j>.)

Gallop	apace,	you	fiery footed	steeds,
Towards	Phoebus'	lodging;	such	a	waggoner
As	Phaethon	would	whip	you	to	the	west,
And	bring	in	cloudy	night	immediately.


You should end up with something like this:


Gallop apace, you fiery footed steeds, Towards  Phoebus'  lodging;  such  a
waggoner As Phaethon would whip you to the west, And bring in cloudy  night
immediately. 

A "Unrectangle Text" menu item is available by pressing the option key,  or
with the key binding <ctrl-c z>. It justifies the text to the left.


# More examples
===============


You can now select a region and experiment : here are some examples applied
to our now favorite passage:

Gallop	apace,	you	fiery footed	steeds,
Towards	Phoebus'	lodging;	such	a	waggoner
As	Phaethon	would	whip	you	to	the	west,
And	bring	in	cloudy	night	immediately.


#	'Deleting'

Gallop 	apace,  	steeds, 
Towards	Phoebus'	a       	waggoner    
As     	Phaethon	you     	to          	the    	west,       
And    	bring   	in      	cloudy      	night  	immediately.

#	'Copying, selecting the first two lines and appending'

Gallop 	apace,  	you     	fiery-footed	steeds,	you         	fiery-footed
Towards	Phoebus'	lodging;	such        	a      	waggoner    	lodging;    	such        
As     	Phaethon	would   	whip        	you    	to          	the         	west,       
And    	bring   	in      	cloudy      	night  	immediately.

#	'Copying, selecting the second column and inserting'

Gallop 	you     	fiery-footed	apace,  	you     	fiery-footed	steeds,
Towards	lodging;	such        	Phoebus'	lodging;	such        	a      	waggoner    
As     	would   	whip        	Phaethon	would   	whip        	you    	to          	the	west,
And    	bring   	in      	cloudy      	night  	immediately.

#	'Twiddling'

Gallop 	apace,  	fiery-footed	you     	steeds,
Towards	Phoebus'	such        	lodging;	a      	waggoner    
As     	Phaethon	whip        	would   	you    	to          	the	west,
And    	bring   	in      	cloudy      	night  	immediately.

#	'Sorting Columns'

Gallop 	apace,  	lodging;	such        	steeds,
Towards	Phoebus'	would   	whip        	a      	waggoner    
As     	Phaethon	you     	fiery-footed	you    	to          	the	west,
And    	bring   	in      	cloudy      	night  	immediately.

#	'Selecting the first two lines and reverse sorting rows'

you         	steeds, 	apace,      	Gallop      	fiery-footed
waggoner    	Towards 	such        	Phoebus'    	lodging;    	a           
As          	Phaethon	would       	whip        	you         	to          	the	west,
And         	bring   	in          	cloudy      	night       	immediately.

#	'Selecting all four lines and inserting rows numbers'

1	Gallop 	apace,  	you     	fiery-footed	steeds,
2	Towards	Phoebus'	lodging;	such        	a      	waggoner    
3	As     	Phaethon	would   	whip        	you    	to          	the	west,
4	And    	bring   	in      	cloudy      	night  	immediately.

etc. etc.

	  	
	----------------------------------------------------------------------


# Key Bindings
==============

All the key bindings will use 'ctrl-c' (c for columns !). 

Hit 'ctrl-c', release, then hit one of the following letters :

	<ctrl-c a>    to <a>ppend columns
	<ctrl-c b>    to show info about <b>indings
	<ctrl-c c>    to <c>opy columns
	<ctrl-c d>    to <d>elete columns
	<ctrl-c e>    to <e>qualize columns
	<ctrl-c i>    to <i>nsert columns
	<ctrl-c j>    to fully <j>ustify text
	<ctrl-c k>    to <k>olorize <k>olumns
	<ctrl-c m>    to put text in <m>ulticolumns
	<ctrl-c n>    to <i>nsert rows numbers
	<ctrl-c o>    to sort each row in increasing <o>rder
	<ctrl-c p>    to com<p>lete rows
	<ctrl-c r>    to sort each row in <r>everse order
	<ctrl-c s>    to change the columns <s>eparator
	<ctrl-c t>    to <t>widdle columns
	<ctrl-c u>    to <u>nequalize columns
	<ctrl-c v>    to set the margin <v>alues for columnizing
	<ctrl-c x>    to cut columns (e<x>tract them and copy in clipboard)
	<ctrl-c z>    to unrectangle text


The menu item "Text --> Columns -> Columns Utilities -> Columns Bindings",
bound to <ctrl-c b>, will display all of the key bindings available.


# End of Tutorial.

